2015-08-04

使用Spring构建一个 RESTful Web Service

Spring官方英文原文：Building a RESTful Web Service

构建目标

构建一个如下接收HTTP GET请求的的服务

http://localhost:8080/greeting

并且返回用于描述greeting内容的JSON数据

1	{"id":1,"content":"Hello, World!"}

你也可以自定义一个可选的name参数来定制返回的问候语

http://localhost:8080/greeting?name=User

带上name参数条件后返回结果会将原来的World替换

1	{"id":1,"content":"Hello, User!"}

环境准备

任意Java IDE
JDK 1.7+
Maven 2.0+
Spring 4+

如何完成

和大多数Spring入门教程相同，你可以一步一步来，或者跳过你已熟悉的基本设置步骤，无论何种方式，最终将得到可正常运行的代码。
如果一步一步来，直接跳到下一节（使用Maven构建工程）
如果跳过可直接clone如下代码

git clone https://github.com/spring-guides/gs-rest-service.git

使用Maven构建工程

└── src
    └── main
        └── java
            └── hello

pom.xml文件内容

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.springframework</groupId>
    <artifactId>gs-rest-service</artifactId>
    <version>0.1.0</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.2.5.RELEASE</version>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>

    <properties>
        <java.version>1.8</java.version>
    </properties>


    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

    <repositories>
        <repository>
            <id>spring-releases</id>
            <url>https://repo.spring.io/libs-release</url>
        </repository>
    </repositories>
    <pluginRepositories>
        <pluginRepository>
            <id>spring-releases</id>
            <url>https://repo.spring.io/libs-release</url>
        </pluginRepository>
    </pluginRepositories>
</project>

创建一个资源描述类

有了工程目录和Maven之后，可以开始创建 web service。
首先考虑服务间交互（service interactions）。
这个服务要处理greeting的GET请求，其可包含一个可选的name 参数。这个请求应当返回一个状态为200 OK 的响应，body中包含描述greeting内容的JSON字符串，如下：

{
    "id": 1,
    "content": "Hello, World!"
}

其中id是greeting内容的唯一标识，content是greeting内容的文本描述字段。

为了多greeting响应建模，可以创建一个资源描述类。提供一个包含field，constructors，getter/setter的java对象：

src/main/java/hello/Greeting.java

package hello;

public class Greeting {

    private final long id;
    private final String content;

    public Greeting(long id, String content) {
        this.id = id;
        this.content = content;
    }

    public long getId() {
        return id;
    }

    public String getContent() {
        return content;
    }
}

如上所见，Spring使用了Jackson JSON类库自动生成greeting对象的JSON字符串。

创建资源类控制器

在使用Spring构建RESTful web services的时候，使用资源类控制器来处理http请求。资源控制类可以通过@RestController 注解来定义，下面的GreetingController控制器处理来自/greeting 的GET请求并返回一个Greeting类的实例：

src/main/java/hello/GreetingController.java

package hello;

import java.util.concurrent.atomic.AtomicLong;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GreetingController {

    private static final String template = "Hello, %s!";
    private final AtomicLong counter = new AtomicLong();

    @RequestMapping("/greeting")
    public Greeting greeting(@RequestParam(value="name", defaultValue="World") String name) {
        return new Greeting(counter.incrementAndGet(),
                            String.format(template, name));
    }
}

这个控制类简单明了，但内部做了大量的处理，我们一步一步来分析下。

@RequestMapping注解确保来自/greeting的HTTP请求能映射到greeting()方法上。

上述例子中并没有指定 GET/PUT/POST 等HTTP操作类型，因为注解@RequestMapping 默认映射所有的HTTP 操作类型。使用@RequestMapping(method=GET) 方式来限定类型只能是GET。

使用@RequestParam可将请求参数name的值绑定到greeting 方法的参数上。该参数不是必须的，如果请求中不包含该参数，将使用默认的World。

实现的方法体重创建并返回一个新的Greeting对象，其中并且id实现自增，content根据请求name来构造返回。

一个传统的MVC控制器和RESTful web service控制器关键区别在于对HTTP请求响应内容的创建方式。RESTful web service不是依靠视图技术来包装greeting对象并传递到HTML上，而是直接将Greeting数据内容转换成一个JSON对象直接响应到HTTP response中。

使用Spring4+才有的@RestController注解方式，可直接将返回内容放在HTTP response中，而不是原来的返回到一个HTML页面的方式，它轻易的将请求和响应处理融合在了一起。

Greeting对象必须转换成JSON字符串，有了Spring的消息转换支持，你不需要手动进行转换。转换类MappingJackson2HttpMessageConverter将自动进行这一操作。

运行程序

虽然可以将本服务打成一个WAR包并部署到应用服务器，但更简单的办法是创建一个独立的程序。将所有程序打包成一个可运行的JAR包文件，使用main()方式作为入库执行。使用Spring中嵌入的Tomcat servlet容器替代部原有方式作为运行时环境。

src/main/java/hello/Application.java

package hello;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

@SpringBootApplication是一个很简洁的注解，和下面注解实现的功能一致。

@Configuration用于定义一个加入到Spring上下文的注解。
@EnableAutoConfiguration告诉Spring添加基于classpath设置的bean。
正常情况下需要为一个Spring MVC程序设置@EnableWebMvc 来告诉Spring需要加入classpath，但使用@EnableAutoConfiguration Spring将自动加入。这如同之前配置的DispatcherServlet行为一样。
@ComponentScan 让Spring在hello包下寻找组件，配置和服务类下找到HelloController类。
main方法中使用SpringApplication.run() 方法来启动程序。注意该程序没有任何XML配置文件，也没有web.xml文件。该程序只有Java代码不需要其他任何的设置。

将程序编译成JAR包并执行：

java -jar build/libs/gs-rest-service-0.1.0.jar

测试服务

运行JAR包后，直接访问地址http://localhost:8080/greeting将得到如下反馈：

1	{"id":1,"content":"Hello, World!"}

将name作为请求参数传入，将得到如下反馈：

1	{"id":2,"content":"Hello, User!"}